Identity Management

Introduction

Identity Management provides ways to manage your users identities and their security related information like roles, groups, attributes and credentials. Given that it is a vast area, PicketBox relies on the PicketLink IDM project to provide such capabilities and extensions.

The Identity Management plays a key role in PicketBox. It is responsible to provide ways to access a specific Identity Store to execute operations like:

check if a specific user exists
user credential management (password, certificates, tokens, etc)
query for users, roles, groups and their relationships
user caching
support different identity stores like databases and LDAP repositories.

While PicketLink IDM knows how to manage your users and their security related information using a specific Identity Store, PicketBox knows how to help you authenticate and authorize your users using those information.

Identity Manager

When talking about Identity Management the main component is the Identity Manager. For that, PicketLink IDM provides a well defined interface called org.picketlink.idm.IdentityManager.

When you build the configuration and create the PicketBoxManager the Identity Manager is automatically configured using a specific Identity Store. By default, PicketBox uses a file-based identity store to persist your users identities and related information. But you can always configure different identity stores like databases or LDAP repositories.

How to get the Identity Manager from a PicketBoxManager instance

        PicketBoxManager picketBoxManager = // create and start the manager

        // get the identity manager
        IdentityManager identityManager = picketBoxManager.getIdentityManager();

        // now you can manage your users identities, roles, groups and other security related information

The code above shows how you can get the Identity Manager instance from the PicketBoxManager. After starting the manager you just need to use the PicketBoxManager.getIdentityManager() method.

Managing Users, Roles, Groups and Attributes

In this section we'll cover some examples about how using the Identity Manager interface to manage your users, roles, groups and related attributes.

Before the looking at the examples, check the diagram bellow for a overview about the PicketLink IDM Domain Model.

images/author/download/attachments/51282281/idm_class_model.png

Creating Users

Creating an user

SimpleUser robert = new SimpleUser("robert");

identityManager.add(robert);

robert.setEmail("robert@picketbox.com");
robert.setFirstName("Robert");
robert.setLastName("Junior");

identityManager.updateCredential(robert, new Password("mysecretpassword"));

Creating Roles

Role developerRole = new SimpleRole("developer");

identityManager.add(developerRole);

Role adminRole = new SimpleRole("admin");

identityManager.add(adminRole);

Creating Groups

Group picketboxGroup = new SimpleGroup("The PicketBox Group");


identityManager.add(picketboxGroup);

Creating Membership (Associating users, roles and groups)

Associating users, roles and groups

// associate the robert user with the developer role and developer group
identityManager.grantRole(robert, developerRole);

// associate the robert user as a member of picketboxGroup group.
identityManager.addToGroup(robert, picketboxGroup);

Managing Attributes

Attributes gives you a lot of flexibility when defining additional and custom information for users, roles and groups. It can be used as a metadata where you can define additional behaviour, for example.

All Identity Types (users, roles and groups) can have their attributes managed. Check the example bellow, it shows how to add some security question to an User using only attributes.

Managing attributes for an User

// defining some security questions as attributes
robert.setAttribute(new Attribute<String>("QuestionTotal", "2"));
robert.setAttribute(new Attribute<String>("Question1", "What is favorite toy?"));
robert.setAttribute(new Attribute<String>("Question1Answer", "Gum"));


// defining a multi-valued attribute
robert.setAttribute(new Attribute<String[]>("MultiValuedAttribute", new String[] { "value1", "value2", "value3" }));

assertEquals("2", robert.getAttribute("QuestionTotal").getValue());
robert("What is favorite toy?", robert.getAttribute("Question1").getValue());
assertEquals("Gum", robert.getAttribute("Question1Answer").getValue());

assertEquals("value1", robert.getAttributeValues("MultiValuedAttribute").getValue()[0]);
assertEquals("value2", robert.getAttributeValues("MultiValuedAttribute").getValue()[1]);
assertEquals("value3", robert.getAttributeValues("MultiValuedAttribute").getValue()[2]);

Available Identity Stores

The Identity Manager interfaces is just a Facade for the Identity Management functionality. It relies on different Identity Stores implementations to connect with a specific repository (eg.: databases or LDAP) where your users and security related information are stored.

That said, PicketLink IDM provides different identity stores implementations:

JPA-based, to manage your users using a database.
LDAP-based, to manager your users using a LDAP tree
File-based, to manage your users using the filesystem

based

If you want to manage your users using a database you should consider using this type of identity store. This implementation uses the Java Persistence API(JPA) and only requires that you have properly configured your application to use JPA.

This store comes in two flavors:

With a default and well defined schema
With the necessary support to integrate your own schema

Which one to choose depends on your application requirements. If you do not have a schema you can choose the one we provide. Otherwise, if your application already have a schema where your users and their information are stored you can choose to customize your JPA entities and use your own schema.

For more information, check the JPA-based Identity Store documentation.

LDAP-based

If you want to manage your users using a LDAP server you should consider using this type of identity store. This implementation helps you to connect to your server and integrate your LDAP schema.

For more information, check the LDAP-based Identity Store documentation.

File-based

If you want to manage your users using the filesystem you should consider using this type of identity store. This implementation is not recommended in production environments, for that you should consider a JPA or LDAP based store.

But this store type is very useful when you do not defined a production repository yet, helping you to get started and move later to a more robust repository. It suits well for testing scenarios and development environments.

For more information, check the File-based Identity Store documentation.